////////////////////////////////////////////////////////////////////////
//                                                                    //
// KconfigSize : Linux kernel size and memory usage measurement tool  //
//                                                                    //
// README (English)                                                   //
//                                                                    //
////////////////////////////////////////////////////////////////////////


KconfigSize Introduction
==============================

KconfigSize is a tool to measure the impact to the static size and
memory usage caused by different kernel config items. Once top-level command 
kconfigsize is executed with the configuration file as parameter, the following 
will be executed automatically.

-  Create the .config files for kernel make and build kernel images in order 
   to measure the impact of each target-config-item which is specified by user. 
   Each target-config-item will create one .config file and one kernel image.
-  Measure the kernel image size and calculate the impact caused by each config 
   item.
-  Use kernel image to boot up the target machine and measure the memory usage, 
   then calculate the impact caused by each config item. This process will 
   repeat until all the kernel images are measured.
  
The result of size and memory usage can be represented by Web interface or 
text file.  Representation by web interface uses KconfigWeb.


Build
==============================

Execute below in appropriate directory.

  $ tar xjvf kconfigsize.tar.bz2
  $ cd kconfigsize
  $ ./autogen.sh
  $ make
  $ make install

Executable binaries are installed to kconfigsize/bin/local.

Notice
--------
To build the KconfigSize, the following is necessary. 
(some other tools may be needed)
  - autoconf
  - automake
  - bison
  - flex
  - make
  - gcc

Building and executing have been verified under Linux on i386 platform. 
On arm and mips platform, the process should be OK theoretically, but it has 
not been verified, yet. 

Measure
==============================

(1) Prepare
--------------------

--- 1) necessary environment

In order to perform measurement, necessary environment is as below.
  - Linux kernel source code
    * Just for 2.6 series. 2.4 series is not handled.
  - Python
  - Target machine
    * When measure memory usage, emulator like qemu can be used.


--- 2) target machine setting (for measuring memory usage) 
Target machine must be set like below.
  - Kernel images can be downloaded from host machine by tftp.
  - Console output can be read by host machine with serial console.
  - Target machine should support below commands.
     dmesg, expr, sed, grep
  - Target machine can be rebooted by command of host machine.
Please install the kconfigsize/bin/target/memfree.sh as boot script(/etc/rc?.d)
to target machine. More information about target machine setting and connection 
between target and host, please refer to target_en.txt.


--- 3) applying patch to kernel source(for measuring memory usage) 
In order to measure memory usage, please apply the proper patch to kernel 
source code. Patch is under the kconfigsize/patches directory, So patch can be 
applied according to corresponding kernel version. 


--- 4) create target-config-item list
In order to specify target-config-items, target-config-item list must be 
created. KconfigSize has two measuring approaches, "top-down" and "bottom-up".
Only one approach can be chosen at a time. 

  - top-down approach
    Based on .config file created by user, impact towards the size and memory 
    usage of enabled config items (=y or =m) can be measured. Config items to be
    measured are specified in target-config-item list. 

  - bottom-up approach
    Specify minimum config items which are necessary for booting,  and target-
    config-items. Then impact towards the size and memory usage of target-
    config-items can be measured. minimum config items, target-config-items 
    are all specified in target-config-item list. 
     
the format of target-config-item list is different in  bottom-up and top-down 
approach. For more information, please refer to configure_en.txt file.

--- 5) create configuration file of KconfigSize tool

Create the configuration file according to the environment.
The major config items are as below.(Key name is in the brackets.)

  - name of the measurement(TEST_NAME)
  - output directory of measurement result (DB_PATH)
  - temporary output directory(WORK_PATH)
  -.config file ... only used in top-down approach (KERNEL_CONFIG)
  - target-config-item list (TARGET_LIST)
  - directory of kernel source code (KERNEL_SOURCE)
  - which kind of measurement need to be performed, there are 3 kinds of
    measurement, size only,  memory only, size and memory (DO_TEST)
  
=== below items are necessary only in memory measurement ===
  - command for resetting target machine (RESET_HELPER)
  - command for communicating with target (MEM_MEASURE)
  - copy destination of kernel images for target machine (INSTALL_IMAGE)

There are also some other config items. For more information, please
refer to configure_en.txt file. The configuration example is also available 
under the conf directory.


(2) Measure
--------------------
Executing the command listed below.

$kconfigsize/bin/kconfigsize <tool configuration file>

Creating .config file, making kernel image, measuring image size, rebooting 
target machine and measuring memory usage are automatically executed, and then 
result is output. 


Represent measurement result
==============================

(1) Web interface
--------------------

Measurement result can be viewed by Web browser. Set the http server properly,
 and access the CGI script below.

kconfigsize/bin/local/kconfigweb.cgi

For more information, please refer to kconfigweb_en.txt file.

(2) Text file
--------------------

Created .config file, kernel image and text file of measurement result are put 
in the directory, which is specified by WORK_PATH and TEST_NAME in the tool
configuration file.


(3) Structure of output directory
--------------------

the directory tree of KconfigSize tool and output files
are listed as below.
("*" is a non-negative integer begin from 0.)

/
|
+- <WORK_PATH>/<TEST_NAME>/
|  |
|  +- kernel/
|  |   |
|  |   +- *.bzImage  : compressed kernel image
|  |   +- *.vmlinux  : kernel image
|  |   +- *.config   : kernel .config file
|  |
|  +- work/
|      |
|      +- binder_size_result : kernel size
|      +- indiv_size_result  : size impact
|      +- binder_mem_result  : kernel memory usage
|      +- indiv_mem_result   : memory impact 
|
+- <DB_PATH>/
|  |
|  +- <TEST_NAME>_{td|bu}.db : measuring result file(for KconfigWeb)
|
+- <TESTROOT>/
   |
   +- conf/
      |
      +- kconfigweb.conf     : configuration file used by KconfigWeb
      (If kconfigweb.conf exists, kconfigweb.conf.tmp is output)

More information
==============================

Please refer to documents under docs directory listed below.

--- configure_en.txt
Details of target-config-item list and tool configuration. 

--- target_en.txt
For measuring memory usage, host and target should be connected and set 
properly. This file contains details about how to set it.

--- kconfigweb_en.txt
Details about how to set the Web interface and view the measuring result. 

Information and source code of KconfigSize project can be accessed here.  
http://tree.celinuxforum.org/CelfPubWiki/KernelConfigWeight

Please send suggestions, comments and bugs to here.
<m-ikeda@ds.jp.nec.com>
IKEDA, Munehiro

